"""
Filesystem 模块 - 抽象接口
"""
from abc import ABC, abstractmethod
from typing import AsyncIterator, List, Optional


class IFileSystem(ABC):
    """
    一个标准化的接口，用于与不同的文件存储后端（本地、云存储等）进行交互。
    它同时定义了文件级操作和存储桶级操作。
    """

    # --- 存储桶/目录级别操作 ---

    @abstractmethod
    async def create_bucket(self, bucket_name: str, **kwargs) -> bool:
        """
        创建一个新的存储桶（或在本地文件系统中创建一个根目录）。
        
        Args:
            bucket_name: 存储桶的名称。
            **kwargs: 特定于实现的参数 (例如 S3 中的区域配置)。
        
        Returns:
            如果创建成功或已存在，返回 True。
        """
        raise NotImplementedError

    @abstractmethod
    async def delete_bucket(self, bucket_name: str, **kwargs) -> bool:
        """
        删除一个存储桶。
        
        Args:
            bucket_name: 存储桶的名称。
            **kwargs: 特定于实现的参数。
        
        Returns:
            如果删除成功，返回 True。
        """
        raise NotImplementedError

    @abstractmethod
    async def bucket_exists(self, bucket_name: str, **kwargs) -> bool:
        """
        检查存储桶是否存在。
        
        Args:
            bucket_name: 存储桶的名称。
        
        Returns:
            如果存在，返回 True。
        """
        raise NotImplementedError

    @abstractmethod
    async def list_buckets(self) -> List[str]:
        """
        列出所有可用的存储桶。
        
        Returns:
            一个包含所有存储桶名称的列表。
        """
        raise NotImplementedError

    # --- 文件/对象级别操作 ---

    @abstractmethod
    async def save(
        self,
        stream: AsyncIterator[bytes],
        path: str,
        bucket_name: Optional[str] = None,
        **kwargs
    ) -> str:
        """
        以流式的方式保存一个文件。

        Args:
            stream: 一个包含文件内容的异步字节迭代器。
            path: 文件在存储中的相对路径（Key）。
            bucket_name: (可选) 目标存储桶。如果为 None, 将使用默认配置。
            **kwargs: 其他特定于实现的参数。

        Returns:
            返回保存后文件的完整存储路径或标识符。
        """
        raise NotImplementedError

    @abstractmethod
    async def read(
        self,
        path: str,
        bucket_name: Optional[str] = None,
        **kwargs
    ) -> AsyncIterator[bytes]:
        """
        以流式的方式读取一个文件。

        Args:
            path: 要读取的文件的路径。
            bucket_name: (可选) 所在存储桶。
            **kwargs: 其他特定于实现的参数。

        Yields:
            bytes: 文件内容的字节块。
        """
        raise NotImplementedError
        yield b''  # This is to make it an async generator

    @abstractmethod
    async def delete(
        self,
        path: str,
        bucket_name: Optional[str] = None,
        **kwargs
    ) -> bool:
        """
        删除一个文件。

        Args:
            path: 要删除的文件的路径。
            bucket_name: (可选) 所在存储桶。
            **kwargs: 其他特定于实现的参数。

        Returns:
            如果删除成功，返回 True。
        """
        raise NotImplementedError

    @abstractmethod
    async def exists(
        self,
        path: str,
        bucket_name: Optional[str] = None,
        **kwargs
    ) -> bool:
        """
        检查一个文件是否存在。

        Args:
            path: 要检查的文件的路径。
            bucket_name: (可选) 所在存储桶。
            **kwargs: 其他特定于实现的参数。

        Returns:
            如果文件存在，返回 True。
        """
        raise NotImplementedError

    @abstractmethod
    async def get_presigned_url(
        self,
        path: str,
        bucket_name: Optional[str] = None,
        expires_in: int = 3600,
        **kwargs
    ) -> str:
        """
        获取一个文件的预签名 URL，用于临时授权访问。

        Args:
            path: 文件的路径。
            bucket_name: (可选) 所在存储桶。
            expires_in: URL 的有效时间（秒）。
            **kwargs: 其他特定于实现的参数。

        Returns:
            文件的预签名 URL。
        """
        raise NotImplementedError 